Skip to content

Add coverage-gated well permit to production flow - #89

Merged
karlwaldman merged 2 commits into
mainfrom
codex/well-production-readme-20260811
Aug 11, 2026
Merged

Add coverage-gated well permit to production flow#89
karlwaldman merged 2 commits into
mainfrom
codex/well-production-readme-20260811

Conversation

@karlwaldman

@karlwaldman karlwaldman commented Aug 11, 2026

Copy link
Copy Markdown
Member

Summary

  • add a customer-ready permit-to-production example that reads current well-level coverage before requesting monthly history and accepts only 14 ASCII-digit API numbers
  • make sync/async well-permit search accept production filters without a legacy query, unwrap all supported list/root/nested envelopes, and fail typed on unknown successful shapes instead of silently returning empty
  • release as 1.12.5 and harden every workflow action/checkout, default-branch secret/identity gates, and the PyPI OIDC pipeline with a checksummed verify/publish/readback split

Red / green

  • Red: production nested {data:{well_permits,meta}} fixtures returned the wrong shape; unknown success shapes silently passed; Unicode API digits passed the README guard; a Python 3.8-incompatible test annotation and unpinned workflow actions were detected before publication.
  • Green local: 478 passed / 13 skipped, 62.63% coverage; 15 dedicated sync/async envelope tests; source ruff and mypy clean; 63 storefront surfaces; every workflow YAML parses and every action is full-SHA pinned.
  • Fresh exact candidate artifacts: Twine green; wheel RECORD 53/53 readable entries recursively scanned and claim-clean; clean wheel keyless production smoke 34 rows / 34 unique / 9 core usable; authenticated smoke 72 permits / 72 valid 14-digit ASCII API numbers / 5 known-well production months.

Release safety

Publish only after this exact head is merged through protected main and its default-branch keyed synthetics pass. The release workflow accepts only a tag reachable from protected main, passes only a checksummed artifact to the OIDC publisher, verifies exact public PyPI hashes, and attaches the checked snippet manifest after public readback.

Summary by CodeRabbit

  • New Features
    • Added support for well-permit searches using live filters, optional queries, Texas permit searches, API-number validation, and production lookups.
    • Added documentation for permit-to-production workflows and handling missing production data.
  • Bug Fixes
    • Improved well-permit response handling across synchronous and asynchronous clients.
    • Fixed production search-response processing while preserving existing query compatibility.
  • Release
    • Released version 1.12.5 with updated package metadata and changelog.
  • Reliability
    • Strengthened release verification, artifact validation, workflow security, and automated readiness checks.

@coderabbitai

coderabbitai Bot commented Aug 11, 2026

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@karlwaldman, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 45 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f07b80d1-b886-4321-ab54-148c7abbe5de

📥 Commits

Reviewing files that changed from the base of the PR and between 77f5be9 and 8a91184.

📒 Files selected for processing (5)
  • .github/workflows/publish.yml
  • CHANGELOG.md
  • README.md
  • scripts/package_version.py
  • tests/test_release_readiness.py
📝 Walkthrough

Walkthrough

The SDK adds normalized synchronous and asynchronous well-permit searches. The release workflows now verify artifacts before publishing, validate PyPI readback, attach release assets, pin actions, restrict sensitive jobs, and enforce checkout security.

Changes

Release and API updates

Layer / File(s) Summary
Well-permit search normalization
oilpriceapi/resources/ei/well_permits.py, oilpriceapi/async_resources.py, tests/unit/test_ei_well_permits_resource.py, README.md, tests/test_release_readiness.py
Search methods accept optional queries, support live filters, normalize supported response wrappers, preserve legacy query parameters, and reject malformed responses. Documentation and tests cover permit-to-production handling.
Release artifact verification
.github/workflows/publish.yml, oilpriceapi/version.py, pyproject.toml, CHANGELOG.md
The workflow verifies release identity and package contents, publishes only checksummed artifacts, validates PyPI hashes, and uploads release assets. Version 1.12.5 metadata and changelog entries are added.
Workflow hardening and release checks
.github/workflows/github-pages.yml, .github/workflows/live-tests.yml, .github/workflows/test.yml, .github/workflows/weekly-health.yml, tests/test_release_readiness.py
Workflows pin actions, restrict permissions, harden checkout, set timeouts, and gate sensitive jobs on the default branch. Keyed checks fail when required credentials are missing. Tests enforce these controls.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant VerifyJob
  participant ArtifactStore
  participant PublishJob
  participant PyPI
  participant ReadbackJob
  participant GitHubRelease
  VerifyJob->>ArtifactStore: Upload verified distributions and checksums
  PublishJob->>ArtifactStore: Download and validate checksums
  PublishJob->>PyPI: Publish verified distributions
  ReadbackJob->>PyPI: Compare public distribution hashes
  ReadbackJob->>GitHubRelease: Upload verified snippet manifest and checksum file
Loading

Possibly related PRs

  • OilpriceAPI/python-sdk#52: Adds the well production resource and cycle-time functionality used by the permit-to-production documentation.
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 13.04% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly describes the primary customer-facing change: a coverage-gated well permit-to-production flow.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/well-production-readme-20260811

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🧹 Nitpick comments (2)
.github/workflows/publish.yml (2)

40-48: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Extract the duplicated version-reading script.

Lines 40-48 and 96-104 embed the same inline Python program that parses version from pyproject.toml. Two copies can drift. The repository already keeps helper scripts under scripts/. Move this logic into one script and call it from both steps.

Also applies to: 96-104

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/publish.yml around lines 40 - 48, Extract the duplicated
inline Python version parser from the workflow steps assigning PACKAGE_VERSION
into a single helper script under scripts/. Update both version-reading steps
around PACKAGE_VERSION to invoke that shared script, preserving the existing
pyproject.toml parsing and missing-version failure behavior.

174-200: 🩺 Stability & Availability | 🔵 Trivial

Consider a longer readback budget.

The loop runs 12 attempts with a 5-second sleep. The minimum total wait is about 60 seconds. PyPI JSON API propagation can take longer than that after an upload. If propagation is slow, this job fails after a successful publish, and the release_assets job never runs even though the release is valid.

Increase the attempt count or use an increasing backoff so that a slow index does not block asset attachment.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/publish.yml around lines 174 - 200, Extend the PyPI
readback window in the verification loop around the attempt counter and sleep so
propagation can exceed the current roughly 60-second budget. Increase the retry
count or implement an increasing backoff while preserving the existing hash
validation and successful exit once all distributions are visible.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/publish.yml:
- Around line 138-146: Update the “Verify exact artifact checksums” workflow
step to compare the number of files in dist/ with the number of entries in
artifact.sha256 before publishing. Fail the step when the counts differ, while
preserving the existing sha256sum -c validation and publish configuration.

In `@README.md`:
- Around line 152-155: Validate that the result assigned to summary from
client.well_production.summary() is a dictionary before calling
summary.get("coverage"). If validation fails, raise RuntimeError with the
existing MALFORMED_RESPONSE convention; retain the coverage validation and
subsequent behavior for valid dictionary responses.

In `@tests/test_release_readiness.py`:
- Around line 127-135: Update the WORKFLOWS discovery and its consumers,
including test_every_workflow_pins_actions_and_hardens_each_checkout_step, to
include both *.yml and *.yaml workflow files. Preserve the existing pinning and
checkout-hardening assertions for every discovered workflow.

---

Nitpick comments:
In @.github/workflows/publish.yml:
- Around line 40-48: Extract the duplicated inline Python version parser from
the workflow steps assigning PACKAGE_VERSION into a single helper script under
scripts/. Update both version-reading steps around PACKAGE_VERSION to invoke
that shared script, preserving the existing pyproject.toml parsing and
missing-version failure behavior.
- Around line 174-200: Extend the PyPI readback window in the verification loop
around the attempt counter and sleep so propagation can exceed the current
roughly 60-second budget. Increase the retry count or implement an increasing
backoff while preserving the existing hash validation and successful exit once
all distributions are visible.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 03d23721-b52e-4d3a-a9a6-b766efaba8a4

📥 Commits

Reviewing files that changed from the base of the PR and between ba974eb and 77f5be9.

📒 Files selected for processing (13)
  • .github/workflows/github-pages.yml
  • .github/workflows/live-tests.yml
  • .github/workflows/publish.yml
  • .github/workflows/test.yml
  • .github/workflows/weekly-health.yml
  • CHANGELOG.md
  • README.md
  • oilpriceapi/async_resources.py
  • oilpriceapi/resources/ei/well_permits.py
  • oilpriceapi/version.py
  • pyproject.toml
  • tests/test_release_readiness.py
  • tests/unit/test_ei_well_permits_resource.py

Comment thread .github/workflows/publish.yml
Comment thread README.md
Comment thread tests/test_release_readiness.py
@karlwaldman
karlwaldman merged commit c4e222e into main Aug 11, 2026
7 checks passed
@karlwaldman
karlwaldman deleted the codex/well-production-readme-20260811 branch August 11, 2026 16:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant